Usage

@Serializable

data class Usage(val inputTokens: Usage.InputTokenBreakdown = InputTokenBreakdown(), val outputTokens: Usage.OutputTokenBreakdown = OutputTokenBreakdown(), val raw: JsonElement? = null)

Token-usage tracking, surfaced on completed steps and final results. Per historical parity gap #19, the shape mirrors v6's rich tree — input tokens split into noCache / cacheRead / cacheWrite and output tokens split into text / reasoning plus a raw slot for provider-specific payloads.

Provider prompt caching needs explicit cache-hit metrics; before this split there was no surface for cache-hit metrics.

Backwards compatibility. A secondary constructor accepts the old (promptTokens, completionTokens, totalTokens?) shape and maps each value into inputTokens.total / outputTokens.total. Computed properties promptTokens / completionTokens / totalTokens read back from the nested tree so existing accumulators and assertions keep working unchanged.

Constructors

Usage

constructor(inputTokens: Usage.InputTokenBreakdown = InputTokenBreakdown(), outputTokens: Usage.OutputTokenBreakdown = OutputTokenBreakdown(), raw: JsonElement? = null)

constructor(promptTokens: Int, completionTokens: Int)

Legacy flat (promptTokens, completionTokens) constructor — unambiguous because BOTH params are required. The primary constructor's Usage() no-arg path goes through default InputTokenBreakdown() / OutputTokenBreakdown().